The XCMD OSAX allows off the shelf XCMD that does not use HyperCard specific callback to be used directly in AppleScript. This is a prototype osax to see if the osax is general enough to cover most the the XCMD available out there. In the final version we will have tool to make the installation of the XCMD easier, but that have to wait until the design is finalized. In the mean time, you have to depend on an aete editor to edit the aete and ResEdit to add the XPRM resource. The TMPL of the XPRM resource is included in the OSAX and the following is further detail about the XPRM resource.
To install a XCMD in the XCMD osax, it is necessary to copy the XCMD and its associated resource into the osax. It is also necessary to define the aete for the XCMD so that AppleScript knows the syntax of the XCMD parameters, and it is necessary to define a XPRM resource about the XCMD parameters. Some of the information are defined in both resources, but this is necessary because at run time the osax will depend on the XPRM and will not parse the aete because that would be too slow.
Obviously the information should be consistent between the aete and the XPRM but they need not be identical. The parameter ordering in the aete is for AppleScript, so the direct parameter comes first but the parameters ordering should be such that the string of the keywords look natural in English or other dialect. The parameter ordering in the XPRM should strictly be the order to be passed to the XCMD. The order is often the same and at least similar because most XCMD parameter are built that way, but they need not be the same and can be rearranged to make better AppleScript statement. The data type of the parameter is usually the same in both the aete and the XPRM, but you are free to have them differ if that works better for your XCMD. The keywords and command name used in aete are for AppleScript and the keywords used in XPRM is for HyperTalk. They need not be the same in both in resource. So an aete keyword can be in multiple words while the corresponding XPRM one should be exactly what HyperTalk expects. Even the number of parameters need not be the same in the aete and the XPRM. Obviously the number of parameters in the XPRM should agree with the XCMD, but you are free to omit them in the aete if you don't think it make sense in AppleScript. There are some special parameters that you can specified in the aete that is not in the XPRM. So there is a lot of flexibility to make the XCMD appears naturally in an AppleScript context.
The first items in the XPRM is the resource type and the resource name of the XCMD/XFCN so the XCMD can be loaded. Resource name is used instead of resource id so that one can have a very clear idea which XCMD he is using when he is reading the resource. Next is the description of the parameters. For each parameter there is the four character keyword and datatype, a 8 bit flag and a text string. The bit flags has the following meanings.
Bit 0 and 1 - the dimension of the list array: the idea is that a lot of the XCMD are really operating on list rather than on text string except that in HyperTalk list is mimicked by text string. In AppleScript, we should restore the real meaning of such XCMD and let them operate on lists. For example the XCMD to remove duplicate lines are really osax to remove duplicate items from list to make it into a set. If the value of the bit field is 0b00, then the parameter is not a list. If it is 0b01 or 0b10, then the parameter is a 1 or 2 dimensional array, and the first one or two character of the text string is the delimiter. The parameter is first converted from a list to a text string using the delimiter before it is passed to the XCMD. If the list is one dimensional array and the delimiter can only be changed at run time, then the bit field should be 0b11 and the delimiter can show up as Apple Event parameter with keyword "dlmt" to override the XPRM value. This delimiter parameter may or may not be a parameter in the XCMD.
Bit 3 - has Keyword, even though XCMD parameters are positional, some of them has convention so that optional keyword parameter of the form xxxx=yyyy can be used. If that is the case the bit should be set for that parameter in the XPRM. The keyword will be in the text string field of the parameter and it should include the '=' character if it is used. The '=' is sometimes not used and then they can be omitted. For example some Boolean parameter such as "DontResolveAlias" is just passed in as is when it is true and omitted if it is false, so there will be no '=' in the keyword text string. In some rare cases we have single character keyword and is used with '=', then again the '=' will be omitted.
Bit 4 - has default, if you want to supply a default value in the parameter, set this bit and put the default value in the text string. With keyword parameter, the default value will come after the '=' character. This means that keyword without the '=' may not have default value.
Bit 5 - skip the parameter in the XCMD if it is not present in the Apple Event. The exact meaning will depend on the other flags.
The last three flags can interact with each other and we shall explain the behaviors of the combination.
No Keyword, no default, no skip: if the parameter is not in the Apple Event, then the parameter is omitted if it is at the end, and empty string is passed to the XCMD if it is not at the end. Note that if you don't want the empty string to be omitted even if it is at the end, then you should use a default of empty string.
No Keyword, no default, skip: if the parameter is not in the Apple Event, then the parameter is omitted.
No Keyword, has default, no skip: if the parameter is not in the Apple Event, then the default value is passed to the XCMD.
No Keyword, has default, skip: if the parameter is not in the Apple Event, then the parameter is omitted if it is at the end, and the default value is passed to the XCMD if it is not at the end.
Has keyword, no default, no skip: if the parameter is not in the Apple Event, then it is omitted. If the parameter is in the Apple Event, its value is appended to the keyword and passed to the XCMD.
Has keyword, no default, skip: just like the previous case except in the case where the data type is a Boolean, then if the parameter is in the Apple Event and its value is false, then it is omitted. If the parameter is in the Apple Event and its value is true, then the keyword is used as the XCMD parameter but the value is not appended. So with the previous case, you can generate "MyKeyWord=TRUE" or "MyKeyWord=FALSE", and with this case you can only generate "MyKeyWord".
Has keyword, has default: If the parameter is not in the Apple Event, then the default value is used. If the parameter is in the Apple Event is used, then the value is appended after the keyword. The keyword is defined to be everything in the XPRM text string up to and including "=".
Bit 7 - the parameter is required. Currently AppleScript does not make sure that all the required parameters are present, so we have an extra check here to reject the operation if the parameter is required but is missing and there is no default.
After all the parameter information, we have the information about the result. We have a 32 bit flag field, most of which are reserved. The one that are currently used are
Bit 0 and 1 - the dimension of the list array, the meaning is the same as in the parameters.
Bit 3 - has error string. One of the biggest problem is that in XFCN, error is returned just like a result. AppleScript prefers a better distinction so there can be better error handling. To distinguish between error and normal result, you may specified that the error message always starts with a fix error string (case sensitive) so that if the result start with the error string, the result is considered to be an error. If the result is always valid, do not set this bit. On the other hand, if a result is always an error as it is the usual case for a XCMD (but not for XFCN), then just set this bit and use an empty error string. Note that it is also possible to invent an error string such as one that start with a null character that can be recognized by the XCMD osax but will never be returned as the normal result of a XFCN. Then it will function both in HyperCard (except no error is actually returned) and in AppleScript.
Bit 4 - if the result is a record, this bit is set if it is a record defined in the aete rather than a user record.
When the result is an array, it can also returned as an Apple Event record or user record. You have to define a list of property name and its data type in the XPRM. If it is a user record then the result data type should be 'usrf', otherwise the result data type should be the record type and bit 4 of the result flag should be set. If it is a user record the property name should be the full name, while it should be the four letter code for the normal Apple Event record. A record would take up more memory than the list because it includes the property name. If you want to have the option to return it as a list and not a record, you may add a parameter with keyword 'labl' and data type typeBoolean to the aete but not to the XPRM. Then you can specify "without label" in your Script.
If you want try to get all the volumes and you have two mount volumes, you will get a result like {“Macintosh HD”, “HDExt”}. If you only have one mounted volume, the result may be {“Macintosh HD”} or “Macintosh HD”. The second form looks nicer, but the first form may be more useful in a script and you want to iterates through all the volumes. In this OSAX, the first form is the default but you may get the first form by specifying “without single item list”. This should be keyword “lsit” in the aete resource but it should not be in the XPRM resource.
